<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of XBEE_CONCALLBACKGET</TITLE>
</HEAD><BODY>
<H1>XBEE_CONCALLBACKGET</H1>
Section: Linux Programmer's Manual (3)<BR>Updated: 04-Mar-2012<BR><A HREF="#index">Index</A>
<A HREF="../index.html">Return to Main Contents</A><HR>

<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

xbee_conCallbackGet, xbee_conCallbackSet
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>#include &lt;<A HREF="file:///usr/include/xbee.h">xbee.h</A>&gt;</B>

<P>
<B>typedef void(*xbee_t_conCallback)(struct xbee *</B><I>xbee</I><B>, struct xbee_con *</B><I>con</I><B>, struct xbee_pkt **</B><I>pkt</I><B>, void **</B><I>data</I><B>);</B>

<P>
<B>xbee_err xbee_conCallbackSet(struct xbee_con *</B><I>con</I><B>, xbee_t_conCallback </B><I>newCallback</I><B>, xbee_t_conCallback *</B><I>oldCallback</I><B>);</B>

<P>
<B>xbee_err xbee_conCallbackGet(struct xbee_con *</B><I>con</I><B>, xbee_t_conCallback *</B><I>curCallback</I><B>);</B>


<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

<P>
<B>xbee_conCallbackSet</B>()

allows you to associate a callback function with a connection, whilst retrieving the current callback.
<P>
<I>con</I>

must be a valid connection, returned from
<B>xbee_conNew</B>().

<I>newCallback</I>

must be either
<B>NULL</B>

(to disable callbacks), or non-NULL to enable callbacks, with the given function address.
<I>oldCallback</I>

can be
<B>NULL</B>

to indicate that you do not wish to retrieve the previously assigned callback.
<P>
<B>xbee_conCallbackGet</B>()

allows you to retrieve the callback function that is currently assigned to the given connection.
<A NAME="lbAE">&nbsp;</A>
<H3>Return Value</H3>

On success these functions will return XBEE_ENONE, otherwise an error number from
<I>enum xbee_errors</I> (as specified in <I>&lt;<A HREF="file:///usr/include/xbee.h">xbee.h</A>&gt;</I>)

<A NAME="lbAF">&nbsp;</A>
<H3>Note</H3>

While a connection has a callback function assigned, use of
<B>xbee_conRx</B>()

will be disabled, and it will return
<B>XBEE_EINVAL</B>.

<A NAME="lbAG">&nbsp;</A>
<H3>Callback Behavior</H3>

For each connection, one callback thread may be active.
Within this thread, the connection's callback function will be executed once for each packet that is received, in the order that they were received.
<P>
This means that if a single callback function is associated with multiple connections, static variables will be unsafe, and the developer should instead use the
<B>void **</B><I>data</I>

that is provided. The
<I>data</I>

parameter is initialized to
<B>NULL,</B>

so you may safely initialize this from within the callback function, or alternatively from outside, by calling
<B>xbee_conDataSet</B>().

<A NAME="lbAH">&nbsp;</A>
<H3>Callback Parameters</H3>

The callback function's parameters are detailed below:
<DL COMPACT>
<DT><I>xbee</I>

<DD>
provides the libxbee instance from which the connection is derived.
<DT><I>con </I>

<DD>
provides the connection that the packet was received by (you may call a variant of
<B>xbee_conTx</B>()

with this from within the callback function).
<DT><I>pkt</I>

<DD>
provides access to the packet that was received.
<P>
<B>NOTE:</B> you must dereference this argument once.

If you leave the argument alone, then libxbee will automatically call
<B>xbee_pktFree</B>()

on the packet after the callback has completed. If you instead re-assign
<B>NULL</B>

to it, libxbee will not call
<B>xbee_pktFree</B>()

on the packet. This is useful if you wish to postpone processing, in which case you must later call
<B>xbee_pktFree</B>().

See the EXAMPLE section for more information.
<DT><I>data</I>

<DD>
provides the data item that you have assigned to the connection, either from within a callback, or by using
<B>xbee_conDataSet</B>().

Again, you must dereference this argument once before use, and you may re-assign it from within the callback function, without calling
<B>xbee_conDataSet</B>().

</DL>
<P>

<A NAME="lbAI">&nbsp;</A>
<H2>EXAMPLE</H2>

<A NAME="lbAJ">&nbsp;</A>
<H3>A simple callback</H3>


<PRE>
#include &lt;<A HREF="file:///usr/include/xbee.h">xbee.h</A>&gt;

void myCallback(struct xbee *xbee, struct xbee_con *con, struct xbee_pkt **pkt, void **data) {
        printf(&quot;received data for connection @ %p\n&quot;, con);
        xbee_conTx(con, &quot;Hello!\n&quot;);
}

struct xbee *xbee;
struct xbee_con *con;

/* initialize xbee, using xbee_setup() */

/* initialize con, using xbee_conNew() */

if (xbee_conCallbackSet(con, myCallback, NULL) != XBEE_ENONE) return;
</PRE>


<A NAME="lbAK">&nbsp;</A>
<H3>A callback that uses the connection's data</H3>


<PRE>

struct myStruct {
        int counter;
        struct xbee_pkt *pkt;
};

void myCallback(struct xbee *xbee, struct xbee_con *con, struct xbee_pkt **pkt, void **data) {
        struct myStruct *ms;
        
        /* allocate storage for the counter &amp; packet */
        if (!(*data)) {
                if ((ms = malloc(sizeof(*ms))) == NULL) return; /* error */
                /* keep hold of the storage */
                *data = ms;
        } else {
                ms = *data;
        }
        
        /* if we are already holding a packet, print a message and return (libxbee will free the packet) */
        if (ms-&gt;pkt) {
                printf(&quot;already holding a packet...\n&quot;);
                return;
        }
        
        /* otherwise increment the counter, and hold on to the packet */
        ms-&gt;counter++;
        ms-&gt;pkt = *pkt;
        
        printf(&quot;received %d packets for connection @ %p\n&quot;, ms-&gt;a, con);
        xbee_conTx(con, &quot;Hello!\n&quot;);
        
        /* don't let libxbee free our packet */
        *pkt = NULL;
}

/* observe the data using xbee_conDataGet() */
</PRE>


<A NAME="lbAL">&nbsp;</A>
<H2>AUTHOR</H2>

Attie Grande &lt;<A HREF="mailto:attie@attie.co.uk">attie@attie.co.uk</A>&gt; 
<A NAME="lbAM">&nbsp;</A>
<H2>SEE ALSO</H2>

<B><A HREF="../man3/libxbee.3.html">libxbee</A></B>(3),

<B><A HREF="../man3/xbee_setup.3.html">xbee_setup</A></B>(3),

<B><A HREF="../man3/xbee_conNew.3.html">xbee_conNew</A></B>(3),

<B><A HREF="../man3/xbee_conTx.3.html">xbee_conTx</A></B>(3),

<B><A HREF="../man3/xbee_conRx.3.html">xbee_conRx</A></B>(3),

<B><A HREF="../man3/xbee_conDataGet.3.html">xbee_conDataGet</A></B>(3),

<B><A HREF="../man3/xbee_conDataSet.3.html">xbee_conDataSet</A></B>(3),

<B><A HREF="../man3/xbee_pktFree.3.html">xbee_pktFree</A></B>(3)

<P>

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DL>
<DT><A HREF="#lbAE">Return Value</A><DD>
<DT><A HREF="#lbAF">Note</A><DD>
<DT><A HREF="#lbAG">Callback Behavior</A><DD>
<DT><A HREF="#lbAH">Callback Parameters</A><DD>
</DL>
<DT><A HREF="#lbAI">EXAMPLE</A><DD>
<DL>
<DT><A HREF="#lbAJ">A simple callback</A><DD>
<DT><A HREF="#lbAK">A callback that uses the connection's data</A><DD>
</DL>
<DT><A HREF="#lbAL">AUTHOR</A><DD>
<DT><A HREF="#lbAM">SEE ALSO</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 18:19:27 GMT, September 04, 2013
</BODY>
</HTML>
